11. 주석: 유지 보수와 변경의 정확성을 높이는 주석 작성 방법

📌 Contents

📌 내용이 낡은 주석

• 코드를 변경할 때, 주석을 변경하지 않는 경우가 많음
• 주석이 구현 시점과 멀어질수록, 주석은 거짓말을 할 가능성이 높음
• 주석이 낡아 버리지 않게, 구현을 변경할 때 주석도 함께 변경하는 것이 좋음
• 이 때 주의해야 할 점이 있음

주석은 실제 코드가 아님을 이해하기

• 프로그래밍에서 클래스와 메서드의 이름이나 주석의 설명은 실제 코드가 아니므로, 실제 내용을 100% 전달할 수 없음
• 최대한 의도가 제대로 전달될 수 있게 클래스와 메서드의 이름을 짓고, 주석을 달아야 함

로직의 동작을 설명하는 주석은 낡기 쉽다

• 코드의 동작을 그대로 설명하는 주석은 코드를 변경할 때마다 주석도 변경해야 할 것입니다.
• 만약 실수로 변경하지 않으면, 로직과 주석 사이에 괴리가 생김
• 주석은 말 전하기 게임과 같아, 말이 전해지면서 조금씩 과장되거나 누락되어, 실제 내용과 다르게 바뀔 가능성이 있음
• 로직을 그대로 설명하는 주석은 코드를 이해하는 데 별다른 도움이 되지 않고, 오히려 가짜 정보가 섞여서 이해하기 어렵게 만들 수 있음
• 주석 떄문에 클래스와 메서드의 이름을 대충 짓게 되는 문제도 있음

📌 주석 때문에 이름을 대충 짓는 예

• 예를 들어 앞에서 말한 로직 구조를 그대로 들어내는 이름 같은 경우는 주석을 이용해 설명을 추가해서 이름을 이해하기 쉽게 할 수 있음
• 이런 경우, 주석은 로직의 동작을 설명하다보니 낡은 주석이 되기 쉬움
• 따라서 이와 같은 메서드는 주석으로 설명을 추가하기보다, 메서드의 이름 자체를 수정하는 것이 좋음
• 메서드의 가독성을 높이면, 주석으로 설명을 추가하지 않아도 되고, 그러면 내용이 낡은 주석이 생길 가능성도 줄어듬

📌 의도와 사양 변경 시 주의 사항을 읽는 이에게 전달하기

• 코드를 읽을 때,
• 코드 유지 보수 시 읽는 사람이 주의를 기울여야 하는 부분은 '이 로직은 어떤 의도를 갖고 움직이는가'
• 사양을 변경할 때 읽는 사람이 주의를 기울여야 하는 부분은 '안전하게 변경하려면 무엇을 주의해야 하는가'
• 주석은 이러한 내용을 담는 것이 좋음

📌 주석 규칙 정리

규칙: 로직을 변경할 때는 반드시 주석도 함께 변경해야 함.
이유: 주석을 제대로 변경하지 않으면, 실제 로직과 달라져 주석을 읽는 사람에게 혼란을 줌.

규칙: 로직의 내용을 단순하게 설명하기만 하는 주석은 달지 않음.
이유: 실질적으로 가독성을 높이지 않고, 주석 유지 보수가 힘듦. 결과적으로 내용이 낡은 주석이 될 가능성이 높음.

규칙: 가독성이 나쁜 로직에 설명을 추가하는 주석은 달지 않음. 대신 로직의 가독성을 높여야 함.
이유: 주석 유지 보수가 힘들고, 갱신되지 않아 낡은 주석이 될 가능성이 높음.

규칙: 로직의 의도와 사양을 변경할 때 주의할 점을 주석으로 달아야 함.
이유: 유지 보수와 사양 변경에 도움이 됨.

📌 문서 주석

• 어떤 프로그래밍 언어는 문서 주석 기능을 제공함
• 문서 주석이란 특정 형식에 맞춰 주석을 작성하면, API 문서를 생성해 줌
• 코드 에더터에 주석의 내용을 팝업으로 표시해 주기 때문에, 메서드 호출 쪽에서 설명 주석을 확인할 수 있어 가독성이 높아짐
• 자바의 Javadoc, C#의 Documentation comments, 루비의 YARD가 있음
• 문서 주석은 개발 효율, 특히 코드의 유지 보수성을 크게 개선해 줌

❓ Questions

❓ 자바스크립트의 문서 주석

• 자바스크립트에도 JSDoc이라는 문서 주석이 있다.
• 이것도 책에서 설명한 것처럼 다른 문서 주석 처럼 특정 형식에 맞춰 주석을 작성하면, API 문서를 생성해 주고, 코드 에더터에 주석의 내용을 팝업으로 표시해 준다.
• JSDoc을 사용하면 개발할 때 좋은점이 많은 것 같아 제대로 공부해 보면 좋을 것 같다.
• JSDoc 공식문서